new (C++)

In the C++ programming language, as well as in many C++-based languages, new is a language construct that dynamically allocates memory on the heap and initialises the memory using the constructor. Except for a form called the "placement new", new attempts to allocate enough memory on the heap for the new data. If successful, it initialises the memory and returns the address to the newly allocated and initialised memory. However if new cannot allocate memory on the heap it will throw an exception of type std::bad_alloc. This removes the need to explicitly check the result of an allocation. A call to delete, which calls the destructor and returns the memory allocated by new back to the heap, must be made for every call to new to avoid a memory leak.

1 Syntax
2 Implementation
3 Releasing dynamically allocated memory
4 Reallocating memory allocated by new[]
5 void* operator new(size_t size)
6 See also
7 References

Syntax

The syntax for new is:

p_var = new typename;

where p_var is a previously declared pointer of type typename. typename can be any basic data type or user-defined object (enum, class, and struct included). If typename is of class type, the default constructor is called to construct the object.

To initialize a new variable created via new, use the following syntax:

p_var = new type(initializer);

where initializer is the initial value assigned to the new variable, or if type is of class type, initializer is the argument(s) to a constructor.

new can also create an array:

p_var = new type [size];

In this case, size specifies the length of one-dimensional array to create. The address of the first element is returned and stored into p_var, so

p_var[n-1]

gives the value of the nth element (counting from 0)

Memory allocated with new must be deallocated with delete to avoid a memory leak. Arrays allocated with new[] must be deallocated with delete[].

int *p_scalar = new int(5); //allocates an integer, set to 5. (same syntax as constructors)
int *p_array = new int[5];  //allocates an array of 5 adjacent integers. (undefined values)

Initializers cannot be specified for arrays created with new. All elements of an array are initialized with the default constructor of the type. If the type does not have a default constructor, this is a compile-time error.

Implementation

In compilers conforming to the ISO C++ standard, if there is not enough memory for the allocation, the code throws an exception of type std::bad_alloc. All subsequent code is aborted until the error is handled in a try-catch block or the program exits abnormally. The program does not need to check the value of the pointer; if no exception was thrown, the allocation succeeded. The implemented operations are defined in the header <new>. In most C++ implementations the new operator can also be overloaded to define specific behaviors.

Releasing dynamically allocated memory

Any memory dynamically allocated with new must be released with a delete command. There are two variants: one for arrays and one for single objects.

int *p_var = new int;
delete p_var;
p_var = 0;
 
int *p_array = new int[50];
delete[] p_array; 
p_array = 0;

Note that the compiler is not required to generate a diagnostic message for using the wrong delete. Furthermore, using the inappropriate deallocator will result in undefined behavior.

Reallocating memory allocated by `new[]`

In contrast to C's realloc, it is not possible to directly reallocate memory allocated with new[]. To extend or reduce the size of a block, one must allocate a new block of adequate size, copy over the old memory, and delete the old block. The C++ standard library provides a dynamic array that can be extended or reduced in its std::vector template.

void* operator new(size_t size)

The C++ language construct that only allocates memory is called void* operator new(size_t size). It is used by new in the allocation phase. It can be overridden per class to define a class specific memory allocator.